APIs and Shades of Gray

API#

APIs are of uttermost importance in clean architecture. An API is a fixed collection of entry points (methods or objects). Every layer may be accessed by elements that live in inner layers via an API.

The separation between layers and the contents of each layer are not always fixed and immutable. A well-designed system should be able to cope with a variety of practical issues. When we design an architecture, it’s very important to know where something is and why, as we’ve mentioned previously in this course. This becomes even more important when we bend the rules. Solutions to many problems are not always black-and-white; similarly, many decisions come in shades of gray.

Let’s keep in mind that it’s important to not break the structure of clean architecture. It’s also important to be very strict about the data flow. If we break the data flow, then we invalidate the whole structure. We should try to not introduce solutions based on a break in the data flow.

Note: There may be instances where this can save money. It may be worth it for you to explore that option if it works for you.

If we do decide to introduce a solution that breaks the data flow, we should leave a warning in both our code and our documentation to explain why we did it. Usually, when we break the interface paradigm to access an outer layer, we do it because of some performance issues. This is because the layered structure can sometimes add overhead to the communication that occurs between elements. We should tell other programmers if this happens. If someone wants to replace the external layer with something different, it’s important for them to know that there’s direct access that’s more implementation-specific.

Example#

As an example, let’s consider a use case that accesses the storage layer through an interface, but it turns out to be too slow. As a result, we then decide to directly access the API of the specific database we’re using, but this breaks the data flow. This is because now an internal layer (use cases) is allowed to access an outer one (external interfaces). If someone wants to replace the specific database we are using with a different one, they need to be aware of this. This is because the new database likely won’t provide the same API entry point with the same data.

If we break the data flow consistently, we may want to consider removing one layer of abstraction. If we do this, we can then merge the two layers that we want to link, as shown in the figure above.